add option to put docstrings on model attributes #1190
Conversation
eli-bl
force-pushed
the
model-attr-docstrings
branch
from
ec3a812 to
0c73307
Compare
|
@dbanty FYI, this was motivated partly by trying to build some HTML docs from a generated client with Sphinx, and finding that Sphinx really does not like how the current class docstrings are formatted. The format only really works if you view the strings as plain text; if it's interpreted either as Sphinx's default |
|
@dbanty Btw, I updated the PR description to clarify the behavior of attribute docstrings in Python. |
end_to_end_tests/docstrings-on-attributes-golden-record/my_test_api_client/client.py
Outdated
Show resolved
Hide resolved
eli-bl
force-pushed
the
model-attr-docstrings
branch
from
80c799d to
e980228
Compare
eli-bl
force-pushed
the
model-attr-docstrings
branch
from
e980228 to
7c3427e
Compare
…1190) Adds a `docstrings_on_attributes` option that causes property descriptions to appear in docstrings on the attributes, instead of in the class docstring. This is a desirable behavior when using documentation generators like Sphinx. This is a non-breaking change; if the option is not set, code generation is exactly the same as before (evidence: the existing golden-record directories have no changes). ## Clarification about how docstrings on attributes work Python does not treat all docstrings the same, in terms of availability at runtime. A docstring on a class or method is available as a `__doc__` attribute— but a docstring on an attribute is not; such a string is just thrown away by the interpreter. If class `A` has attribute `b`, then `A.b.__doc__` will never be a thing— you would have to define `b` as a property getter method instead. However, docstrings on attributes are still valid as per [PEP 257](https://peps.python.org/pep-0257/) as a thing that can be surfaced by other tools. Sphinx _will_ use them when generating documentation, and VS Code _will_ show them as a description in the popup if you hover over an attribute.
Adds a
docstrings_on_attributesoption that causes property descriptions to appear in docstrings on the attributes, instead of in the class docstring. This is a desirable behavior when using documentation generators like Sphinx.This is a non-breaking change; if the option is not set, code generation is exactly the same as before (evidence: the existing golden-record directories have no changes).
Clarification about how docstrings on attributes work
Python does not treat all docstrings the same, in terms of availability at runtime. A docstring on a class or method is available as a
__doc__attribute— but a docstring on an attribute is not; such a string is just thrown away by the interpreter. If classAhas attributeb, thenA.b.__doc__will never be a thing— you would have to definebas a property getter method instead.However, docstrings on attributes are still valid as per PEP 257 as a thing that can be surfaced by other tools. Sphinx will use them when generating documentation, and VS Code will show them as a description in the popup if you hover over an attribute.